Using Inblorb.

How to use this tool, either from the command line or inside the Inform app.

@h What Inblorb is.
Inblorb is a command-line tool which forms one of the components of the
Inform 7 design system for interactive fiction. Inblorb is the successor to
cBlorb (2008), which was itself the successor to perlBlorb (2001).
All installations of Inform 7 contain it, though few users are aware of that.
They typically write sentences such as:

>> Release along with public source text, cover art, and a website.

Inform 7 uses the instructions in such sentences to contribute to the
writing of a script called a "blurb". In effect, this is a detailed set
of instructions for Inblorb to follow, and when the user clicks Release
in the Inform application, the Inblorb tool is called. (This is a slightly
simplified description -- see below for the full details.)

Inblorb has two main jobs: to bind up the translated project, together with
any pictures, sounds, or cover art, into a single file called a "blorb" which
can be given to players on other machines to play; and to produce associated
websites, solution files and so on as demanded by "Release..." instruction(s)
in the source text.

"Blorb" is a general-purpose wrapper format designed as a way to gather
together audiovisual media and bibliographic data for works of IF. The
format was devised and formally specified by Andrew Plotkin around 2000,
and its name is borrowed from that of a magic spell in Infocom's classic
work, "Enchanter". ("The blorb spell (safely protect a small object as
though in a strong box).")

@h Inblorb at the command line.
If you have compiled the standard distribution of the command-line tools
for Inform then the Inblorb executable will be at |inblorb/Tangled/inblorb/|.
Usage is very simple:
= (text as ConsoleText)
	$ inblorb/Tangled/inblorb [OPTIONS] BLURBFILE [BLORBFILE]
=
This follows the given blurb file. Not all blurbs instruct Inblorb to make
a blorb, which is why BLORBFILE is optional.

The OPTIONS are very simple. Inblorb's predecessor cBlorb needed to be told
what platform it was running on, by specifying |-osx|, |-windows| or
|-linux| at the command line, but these have gone. What remains is:

|-verbose| causes Inblorb to print a running narrative of what it's doing;

|-project X| tells Inblorb to assume the usual settings for this project,
which means that BLURBFILE is set to |X/Release.blurb| and BLORBFILE
to |X/Build/output.gblorb|. |X| is usually something like |Whatever.inform|.

@h Inblorb within the Inform user interface.
This is the sequence of events when the user clicks Release in the user
interface application (the "interface"):

(1) The interface calls the Inform 7 compiler as normal except that the
|-release| command-line switch is specified.

(2) If Problems occur, the compiler exits with a return code of 1, and the
interface displays those, and then stops the process.

(3) If no Problems occur, the compiler generates Inform 6 code, and also
two additional files for the project's |Build| folder:
(-a) |Metadata.iFiction|, an iFiction record;
(-b) |Release.blurb|, a blurb file of instructions for Inblorb to follow later.

(4) The interface next calls the Inform 6 compiler. The interface calls it
with the |S| and |D| switches, for strict checking and for debugging, off
instead of on. Inform 6 should certainly not produce syntax errors, though
it will surely produce warnings; all the same it can fail if, say, Z-machine
memory limits are exceeded. The interface should deal with such failures
exactly as it would in a non-Release run.

(5) Inform 6 having returned 0 to indicate success, the interface next calls
Inblorb as follows. Let |Path| be the path to the folder containing the Inform
project being released, which we'll call |This.inform|. Then the interface
should call:
= (text as ConsoleText)
	$ inblorb "Path/This.inform/Release.blurb" "Path/This.inform/Build/output.gblorb"
=
(...) These two filename arguments are the Blurb script for Inblorb to
follow, which was written by Inform 7 at step 3, and the filename of the Blorb
file which it should write. Note that the interface should give this the
extension ".gblorb" if the Glulx setting is in force, and ".zblorb" if
the Z-machine.

(6) Like its predecessors, Inblorb can produce error messages, and it returns
0 (success) or 1 (failure). But the interface doesn't actually need to look
at that, because Inblorb also produces a much fuller report in the form of
an HTML page to be displayed on the Problems tab. This is |StatusCblorb.html|,
in the project's |Build| folder. (This is a change made in 2010: in the past,
the interface simply chose between a generic success and failure page on the
basis of the return code. The filename |StatusCblorb.html| is not hard-wired:
it just happens to be what the Blurb file generated by Inform 7 requests.)

(7) There are no more tools to call, but the interface has one last duty (if
Inblorb succeeded) -- to move the blorb somewhere sensible on disc, where the
user can see it. Leaving it where it is will not do -- the user never looks
inside the Build project of a folder, which on Mac OS X, for instance, is
not even visible. To see what to do, the interface must look at the textual
output from Inblorb, printed to |stdout| (of course the interface is free
to redirect this if it wants to). If Inblorb printed a line in the form:
= (text as ConsoleText)
	Copy blorb to: [[...]]
=
(...) then the interface should do as it's told. For instance:
= (text as ConsoleText)
	Copy blorb to: [[/Users/gnelson/Examples/Bronze Materials/Release/Bronze.gblorb]]
=
(...) If Inblorb printed no such line, the interface should put up a Save As...
dialogue box, and invite the user to choose a destination.
